Import API¶
Overview¶
When a customer is looked up in Issuetracker it can ask the external ticketing system for a list of ticket for that patricular subscriber using an HTTP POST request. The external system provides a JSON list of tickets and corresponding ticket notes which Issuetracker synchronizes with its current list of tickets for that customer. This allows Serverplus agents to have quick and easy access to tickets/notes made from either organization without leaving Issuetracker.
Ticket importing uses the same username / password provided for the Ticket Exporter integration settings.
To enable ticket exporting we require the URL to send requests to.
Request Fomat¶
Issuetracker will make requests for ticket lists with a URL supplied by you. The request will be submitted as an HTTP POST request submitted with the following parameters:
| Name | Description |
|---|---|
| subscriber_id | Unique id for the subscriber who’s ticket information is being requested. This is provided by the billing hooks implemented by the company being supported. If there are no billing hooks in place for this company ticket importing is not supported. |
| username | Username provided with ticket export settings |
| password | Password provided with ticket export settings |
Response Format¶
Responses must be formatted as JSON. The appropriate Content Type should be set to say the data is JSON, like:
- Content-Type: application/json
All dates must be formatted as ISO 8061 dates. ISO 8061 dates have as part of the format a way to provide a timezone offset with the timestamp. If no timezone is provided then the UTC timezone will be used. If times are submitted relative to your timezone you must either convert to UTC or provide the timezone offset with the timestamp.
The JSON response must be an array of Ticket objects. Ticket objects are a container that describes what the problem is about, and what the status of that problem/issue is.
A Ticket object contains one or more TicketNote objects. The TicketNote describes a troubleshooting entry for the ticket made by a single individual/staff member. A TicketNote has note text, a date/time that it occured and can also have a status (where supported, optional otherwise). A Ticket object must have at least 1 TicketNote.
Ticket and TicketNote objects are represented as:
Ticket object JSON¶
| Property Name | Description and Type |
|---|---|
| ticket_id | Unique identifier for the ticket String |
| status | Current status of the ticket. String - Must be one of ‘resolved’, ‘pending’, ‘open’, ‘escalated This property is _optional_ and can be set as null or an empty string. |
| subject | Subject of the ticket. This is a very short description of the problem this ticket is trying to resolve. String - keep under 100 characters |
| note_list | An array of TicketNote objects, described below Array |
TicketNote object JSON¶
| Property Name | Description and Type |
|---|---|
| note_id | Unique identifier for the TicketNote String |
| staff_label | label for the staff member that created this note String |
| date | Date that this note was created ISO 8601 formatted date String - If no timezone is given in the date then UTC is assumed |
| status | status of the TicketNote at the time this note was created. String - one of ‘resolved’, ‘pending’, ‘open’, ‘escalated’ |
| notes | Text body of the notes. String |
Testing¶
We provide a testing tool to submit test queries against your Import URL to make sure that the responses are formatted correctly, and to see what the timestamp is being interpreted as after UTC timezone is applied (if no timezone offset was provided).
The test tool can be found at:
https://tracker.serverplus.com/ticketimport/
We provide a few example responses that can be used with the test tool to see what valid data looks like, and how different error messages are reported with the tool:
- valid data with 1 ticket
- https://tracker.serverplus.com/ticketimport/test1
- valid data with 2 tickets
- https://tracker.serverplus.com/ticketimport/test2
- valid JSON, but passed as single ticket outside of an array
- https://tracker.serverplus.com/ticketimport/test3
- valid JSON, but invalid format of date
- https://tracker.serverplus.com/ticketimport/test4
- invalid JSON
- https://tracker.serverplus.com/ticketimport/test5